/*
 * Copyright © 2018 www.noark.xyz All Rights Reserved.
 *
 * 感谢您选择Noark框架，希望我们的努力能为您提供一个简单、易用、稳定的服务器端框架 ！
 * 除非符合Noark许可协议，否则不得使用该文件，您可以下载许可协议文件：
 *
 *        http://www.noark.xyz/LICENSE
 *
 * 1.未经许可，任何公司及个人不得以任何方式或理由对本框架进行修改、使用和传播;
 * 2.禁止在本项目或任何子项目的基础上发展任何派生版本、修改版本或第三方版本;
 * 3.无论你对源代码做出任何修改和改进，版权都归Noark研发团队所有，我们保留所有权利;
 * 4.凡侵犯Noark版权等知识产权的，必依法追究其法律责任，特此郑重法律声明！
 */
package xyz.noark.network.rpc;

import java.io.Serializable;
import java.util.Collection;

/**
 * RPC路由器，抽象整个业务开发中使用RPC对协议发送接口
 *
 * @author 小流氓[176543888@qq.com]
 * @since 4.0
 */
public interface RpcRouter {
    /**
     * 给玩家发送一个协议
     *
     * @param playerId 玩家ID
     * @param opcode   协议编号
     * @param protocol 协议对象
     */
    void sendToClient(Serializable playerId, Serializable opcode, Object protocol);

    /**
     * 给指定玩家列表群发一个协议
     *
     * @param playerIdList 玩家ID列表
     * @param opcode       协议编号
     * @param protocol     协议对象
     */
    void broadcastToClient(Collection<Serializable> playerIdList, Serializable opcode, Object protocol);

    /**
     * 异步RPC, 向指定一个服务器节点发送一个Rpc请求，但没有返回结果
     *
     * @param serverUid 服务器UID = 服务器类型 * 100W + SID
     * @param opcode    本次请求的协议编号 * @param protocol 本次请求的协议对象
     * @param <T>       本次请求返回协议对象的类型Class
     */
    <T> void asyncCall(int serverUid, Serializable opcode, Object protocol);

    /**
     * 异步RPC, 向指定一个服务器节点发送一个Rpc请求，并异步处理返回结果。
     * <p>
     * 这里有个约定，请求在哪个执行线程组，返回执行逻辑也是这个线程组在执行，所次用担心线程安全问题
     * </p >
     *
     * @param serverUid 服务器UID = 服务器类型 * 100W + SID
     * @param opcode    本次请求的协议编号
     * @param protocol  本次请求的协议对象
     * @param ackClass  本次请求返回协议对象的类型
     * @param callback  异步回调的处理方法，注册有些逻辑要处理超时噢
     * @param <T>       本次请求返回协议对象的类型Class
     */
    <T> void asyncCall(int serverUid, Serializable opcode, Object protocol, Class<T> ackClass, RpcCallback<T> callback);

    /**
     * 同步RPC, 向指定一个服务器节点发送一个Rpc请求，并同步处理返回结果。
     *
     * @param serverUid 服务器UID = 服务器类型 * 100W + SID
     * @param opcode    本次请求的协议编号
     * @param protocol  本次请求的协议对象
     * @param ackClass  本次请求返回协议对象的类型
     * @param <T>       本次请求返回协议对象的类型Class
     * @return 本次请求返回协议对象
     */
    <T> T syncCall(int serverUid, Serializable opcode, Object protocol, Class<T> ackClass);
}